Spec docs: audit fixes, and duplicate-content-id emitted - #265

Fixes the spec docs audit (about 107 findings), re-checked against main after #257 and #262. Each statement was checked against the engine, schemas, data and packs. Changed and new examples were run through the current engine.

Code (own commit)

• Engine: loadRuleset now reports duplicate-content-id (data id, pack) when two content items of one pack share an ID. Before, the code was published but never emitted, and the later item replaced the earlier one silently. Adds a conformance case and a patch changeset for spec and engine.

Docs, by file

• engine-core.md
  • unknown-situational replaces the wrong unknown-id on an adjust.
  • Aura entries: the activation footnote, the applyEffect aura check, merging per aura and applier, the aura immunity ID, and a new Auras section.
  • The pack limit on fields queries (Spec: tag targets reach only packs that meet over the tag #224).
  • Errors: formula errors, auras, copy limits and appliers.
  • content-hidden bullets merged into one.
  • Action tags aren't in computeSheet output.
  • Computed values in action-time effects (Spec: derived parameters, computed values in action-time effects, bounds on an action's own parameter (#251, #252) #262).
  • duplicate-content-id in loadRuleset step 3.
• engine-interface.md
  • setField in the change types and in copy queries.
  • appliers on the five calls that take it.
  • Error kinds formula and build.
  • Full shapes for choices (type, inactive), offers (create) and the applyChanges output.
  • Rules-issue IDs, and unchoose by owner.
• upgrades.md
  • Steps that remove a pick also remove its addAs: copy copy, and adoptStandard skips pick copies.
  • Narrowing now lists a grant's available and added bounds.
  • A given parameter that becomes derived is param-type-changed.
  • A bounds-only params entry isn't a parameter of the pack that declares it.
  • Notes on change IDs and state-removed renames, and a cleaned-up interface-change paragraph.
• effects.md
  • Ops table: a params row, the current changes and option value shapes, and fields targets.
  • Property table: scope, plus the full target and value.
  • effectsWhen applies to holder effects only.
  • Changes steps take the ops changes and action.
  • Stacking wording.
  • Examples follow the packs: effectsWhen gates and Vexed with appliedBy: self.
  • A pointer from an incoming then to batch-scoped situational copy-state costs (Spec: a situational choice's changes reach held copies' state (#244) #257).
• content.md
  • Content items and Choices tables are complete.
  • The Null Field aura now copies the pack (it broke link-field-mismatch).
  • The elemental connection example uses an ID literal.
  • Aura gates, the rules-level immunity owner, of: integer errors, the copyNames link and the type label.
• characters.md: who fills in appliedBy.
• display-hints.md: an unavailable activation is still a content-group member.
• dice-and-actions.md
  • The Fate outcome example is now valid (it gains a result).
  • Reactions go through situational choices.
  • to: applied in the steps table and the finished-action routing; it is dropped from the from routes.
  • Action scope and label, roll part and roll item properties, allocate tags and prompt, and the dNz and comparison notations.
  • Every safety limit, recommend: '#done', and the stray "(0100)"/"(0108)" removed.
  • The parameter conflict wording, and release notes for params.
  • Healing Grace bounds spend with graceEnd.
  • Clock actions and content action effects.
• engine-actions.md
  • The errors startAction throws: invalid-param, unknown-follow-up, unknown-reference, not-addable, unknown-role, unknown-tag and invalid-face.
  • Allocate tags in the policy.
  • self computed values.
  • Situational choices with incoming.
  • Log fields for a rolled amount.
• formulas.md
  • appliedBy, the applier bound-in row, and grant and i types.
  • Roots of changes and action effects, derived parameters, and a situational choice's copy changes (Spec: a situational choice's changes reach held copies' state (#244) #257).
  • steps values and group passes, and release.where.
  • Every missing expected type: band total, aura size, follow-up character, appliedBy, activeWhen, effectsWhen, param bounds and a derived formula.
  • Aggregate and fixed-root lists.
• i18n.md and the en.yaml header
  • The invalid-added-param.<reason> variants, including undeclared.
  • Added-parameter names and descriptions.
  • The invalid-situational-change text covers Spec: a situational choice's changes reach held copies' state (#244) #257's copies.
• packs.md
  • LicenseRef- licenses: credit and the permission notice, which the build doesn't check.
  • The 5e/srd-5.2 path.
  • The full rules-document list, and params effects in extensions.
• README.md: "the official packs of a dozen games", the doc-map rows, and what a fixed set's specVersion means.
• rules-and-fields.md: the intro topic list, and the reaction wording now matches its example.
• versioning.md: a fixed set's specVersion stays when the version moves.
• Data descriptions
  • effect-operations (option flags, params with the Spec: added-param conflicts follow the effects; from: self items never clash (#222) #226 exemption and Effects can't read computed values, and nothing derives a value from an action's parameters #251/A params effect can't bound a parameter the action already declares #252, order)
  • stacking-policies (spansFields)
  • change-types (adjust, applyEffect, unchoose)
  • rules-issue-codes
  • upgrade-steps
  • error-codes (duplicate-id, unknown-reference)
  • formula-context (self, params)
  • safety-limits (action effects)
  • dice-modifiers (notation forms, rerollOnce count)
  • the character schema's applied.aura (types regenerated)

Each area has a patch changeset for @opencharacter/spec.

Skipped

• README "0.3.0": still correct (SPEC_VERSION is 0.3.0; version-packages moves it).
• Already covered by Spec: a situational choice's changes reach held copies' state (#244) #257 and Spec: derived parameters, computed values in action-time effects, bounds on an action's own parameter (#251, #252) #262:
  • engine-core situational copies
  • the describeAction derived and addedBounds
  • the invalid-situational-change reasons
  • content.md "Reading"
  • effects.md derived params and bounds
  • the rules-and-fields Spec: a situational choice's changes reach held copies' state (#244) #257 note
• formula-context.json's roll-effect roll: not extended. The engine binds only item, self and tags there. formulas.md now says the same (see below).
• boundBy in i18n.md: packages/text doesn't use it.

Found, not fixed here (follow-ups)

• Checker vs engine: the formula checker types a roll effect's roll with total, faces, kept and empty. At run time the engine binds only item, self and tags, so such a formula loads and then fails.
• Clock actions: load doesn't check content's op: action effects at a clock action's tagged steps. One that hands off, or runs an action with a choice, allocate or handoff step, makes the clock action pause. This needs an issue (invalid-clock-action at load).
• packages/text: typeKey ignores a content type's label, which the validator honours.
• Packs: draw-steel-heroes Healing Grace still bounds graceRecoveries rather than spend. 5e-srd-5.2 Vexed still uses flags.me.

Checks

pnpm check passes. One timing test flaked under load and passes on its own. pnpm build:website checks 2024 links with 0 broken. pnpm release:check passes.